<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Constructing ECLiPSe data
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot007.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot009.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc16">3.1</A>&nbsp;&nbsp;Constructing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data</H2><UL>
<LI><A HREF="embroot008.html#toc10">ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> atoms and functors</A>
<LI><A HREF="embroot008.html#toc11">Building ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms</A>
<LI><A HREF="embroot008.html#toc12">Building atomic ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms</A>
<LI><A HREF="embroot008.html#toc13">Building ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> lists</A>
<LI><A HREF="embroot008.html#toc14">Building ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> structures</A>
</UL>

<A NAME="toc10"></A>
<H3 CLASS="subsection"><A NAME="htoc17">3.1.1</A>&nbsp;&nbsp;ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> atoms and functors</H3>
<A NAME="@default38"></A>
<A NAME="@default39"></A>
<A NAME="@default40"></A>
<PRE CLASS="verbatim">
    /* ECLiPSe code */
    S = book("Gulliver's Tales","Swift",hardback,fiction),
</PRE>
In the above structure 'hardback' and 'fiction' are atoms. 'book'
is the functor of that structure, and it has an arity (number
of arguments) of 4.<BR>
<BR>
Each functor and atom is entered into a dictionary, and is always
referred to by its dictionary entry. Two classes, <CODE>EC_atom</CODE>
and <CODE>EC_functor</CODE> are used to access such dictionary entries.<BR>
<BR>
The 'Name' method applies to both, to get their string form.
The 'Arity' method can be used to find out how many arguments
a functor has.
<PRE CLASS="verbatim">
    /* C++ code */
    EC_functor book("book",4);
    EC_atom hardback("hardback");

    if (book.Arity()) == 4) .. /* evaluates to true */
    if (book == hardback) ..   /* evaluates to false */
    s = hardback.Name();       /* like s = "hardback"; */
</PRE>
<A NAME="toc11"></A>
<H3 CLASS="subsection"><A NAME="htoc18">3.1.2</A>&nbsp;&nbsp;Building ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms</H3>
<A NAME="@default41"></A>
<A NAME="@default42"></A>
<A NAME="@default43"></A>
The <CODE>pword</CODE> C data type is used to store ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms. In C++ the
<CODE>EC_word</CODE> data type is used. This is used for any C type as well
as for ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> structures and lists. The size remains fixed in all
cases, since large terms are constructed on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> global stack.<BR>
<BR>
<A NAME="@default44"></A>
The consequences of this are that terms will be garbage collected
or moved so terms do not survive the execution of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. In
particular, one cannot build such terms asynchronously while
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is running, for example this precludes building terms from
within a signal handler unless it can make sure that ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> has
yielded when it is running.<BR>
<BR>
<A NAME="toc12"></A>
<H3 CLASS="subsection"><A NAME="htoc19">3.1.3</A>&nbsp;&nbsp;Building atomic ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms</H3>
It is possible to simply cast from a number of simple C++ types to
build an <CODE>EC_word</CODE> In addition, functions exist for creating
<A NAME="@default45"></A>
new variables, and for the nil which terminates ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> lists.
In C++ you can just cast.
<PRE CLASS="verbatim">
    /* making simple terms in C++ */
    EC_word w;
    EC_atom hardback("hardback");
    w = (EC_word) "Swift";
    w = (EC_word) hardback;
    w = (EC_word) 1.002e-7;
    w = (EC_word) 12345;
    w = (EC_word) nil();
    w = (EC_word) newvar();

    /* ECLiPSe equivalent code */
    P1 = "Swift",
    P2 = hardback,
    P3 = 1.002e-7,
    P4 = 12345,
    P5 = [],
    P6 = _,
</PRE>
<A NAME="toc13"></A>
<H3 CLASS="subsection"><A NAME="htoc20">3.1.4</A>&nbsp;&nbsp;Building ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> lists</H3>
<A NAME="@default46"></A>
The <CODE>list(head,tail)</CODE> function builds a list out of two terms. Well
formed lists have lists as their tail term and a nil ("[]") at the end, or a
variable at the end for difference lists.
<PRE CLASS="verbatim">
    /* making the list [1, "b", 3.0] in C++ */
    EC_word w = list(1, list("b", list(3.0, nil())));
</PRE>
The following example shows how you can write functions to build
variable length lists.
<PRE CLASS="verbatim">
/* function to build a list [n,n+1,n+2,.....,m-1,m] */
EC_word fromto(int n, int m)
{
    EC_word tail = nil();
    for(int i = m ; i &gt;= n ; i--)
        tail = list(i,tail);
    return tail;
}
</PRE>
The list is constructed starting from the end, so at all points during its
construction you have a valid term. The interface is designed to
make it hard to construct terms with uninitialised sub-terms, which is
what you would need if you were to construct the list starting with
the first elements.<BR>
<BR>
<A NAME="toc14"></A>
<H3 CLASS="subsection"><A NAME="htoc21">3.1.5</A>&nbsp;&nbsp;Building ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> structures</H3>
<A NAME="@default47"></A>
<A NAME="@default48"></A>
<A NAME="@default49"></A>
The <CODE>term(functor,args..)</CODE> function is used to build ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
structures. A number of different functions each with a different
number of arguments is defined so as not to disable C++ casting
which would be the case if we defined a function with variable
arguments.
<PRE CLASS="verbatim">
    /* making s(1,2,3) in C++ */
    EC_functor s_3("s",3);
    EC_word w = term(s_3,1,2,3);
</PRE>
The above interface is convenient for terms with small fixed arities,
for much larger terms an array based interface is provided.
<PRE CLASS="verbatim">
    /* making s(1,2,..,n-1,n) */
    EC_word args[n];
    for(int i=0 ; i&lt;n ; i++)
        args[i] = i+1;
    EC_word w = term(EC_functor("s",n),args);
</PRE>
<HR>
<A HREF="embroot007.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot009.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
